1 module hip.jni.android.hardware_buffer; 2 3 /* 4 * Copyright 2017 The Android Open Source Project 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 /** 20 * @file hardware_buffer.h 21 * @brief API for native hardware buffers. 22 */ 23 /** 24 * @defgroup AHardwareBuffer Native Hardware Buffer 25 * 26 * AHardwareBuffer objects represent chunks of memory that can be 27 * accessed by various hardware components in the system. It can be 28 * easily converted to the Java counterpart 29 * android.hardware.HardwareBuffer and passed between processes using 30 * Binder. All operations involving AHardwareBuffer and HardwareBuffer 31 * are zero-copy, i.e., passing AHardwareBuffer to another process 32 * creates a shared view of the same region of memory. 33 * 34 * AHardwareBuffers can be bound to EGL/OpenGL and Vulkan primitives. 35 * For EGL, use the extension function eglGetNativeClientBufferANDROID 36 * to obtain an EGLClientBuffer and pass it directly to 37 * eglCreateImageKHR. Refer to the EGL extensions 38 * EGL_ANDROID_get_native_client_buffer and 39 * EGL_ANDROID_image_native_buffer for more information. In Vulkan, 40 * the contents of the AHardwareBuffer can be accessed as external 41 * memory. See the VK_ANDROID_external_memory_android_hardware_buffer 42 * extension for details. 43 * 44 * @{ 45 */ 46 47 // #include <inttypes.h> 48 49 import core.stdc.stdint; 50 import hip.jni.android.rect; 51 import hip.jni.android.android_api; 52 53 /** 54 * Buffer pixel formats. 55 */ 56 enum AHardwareBuffer_Format { 57 /** 58 * Corresponding formats: 59 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 60 * OpenGL ES: GL_RGBA8 61 */ 62 AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1, 63 64 /** 65 * 32 bits per pixel, 8 bits per channel format where alpha values are 66 * ignored (always opaque). 67 * Corresponding formats: 68 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM 69 * OpenGL ES: GL_RGB8 70 */ 71 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2, 72 73 /** 74 * Corresponding formats: 75 * Vulkan: VK_FORMAT_R8G8B8_UNORM 76 * OpenGL ES: GL_RGB8 77 */ 78 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3, 79 80 /** 81 * Corresponding formats: 82 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16 83 * OpenGL ES: GL_RGB565 84 */ 85 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4, 86 87 /** 88 * Corresponding formats: 89 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT 90 * OpenGL ES: GL_RGBA16F 91 */ 92 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16, 93 94 /** 95 * Corresponding formats: 96 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32 97 * OpenGL ES: GL_RGB10_A2 98 */ 99 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b, 100 101 /** 102 * Opaque binary blob format. 103 * Must have height 1 and one layer, with width equal to the buffer 104 * size in bytes. Corresponds to Vulkan buffers and OpenGL buffer 105 * objects. Can be bound to the latter using GL_EXT_external_buffer. 106 */ 107 AHARDWAREBUFFER_FORMAT_BLOB = 0x21, 108 109 /** 110 * Corresponding formats: 111 * Vulkan: VK_FORMAT_D16_UNORM 112 * OpenGL ES: GL_DEPTH_COMPONENT16 113 */ 114 AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30, 115 116 /** 117 * Corresponding formats: 118 * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32 119 * OpenGL ES: GL_DEPTH_COMPONENT24 120 */ 121 AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31, 122 123 /** 124 * Corresponding formats: 125 * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT 126 * OpenGL ES: GL_DEPTH24_STENCIL8 127 */ 128 AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32, 129 130 /** 131 * Corresponding formats: 132 * Vulkan: VK_FORMAT_D32_SFLOAT 133 * OpenGL ES: GL_DEPTH_COMPONENT32F 134 */ 135 AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33, 136 137 /** 138 * Corresponding formats: 139 * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT 140 * OpenGL ES: GL_DEPTH32F_STENCIL8 141 */ 142 AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34, 143 144 /** 145 * Corresponding formats: 146 * Vulkan: VK_FORMAT_S8_UINT 147 * OpenGL ES: GL_STENCIL_INDEX8 148 */ 149 AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35, 150 151 /** 152 * YUV 420 888 format. 153 * Must have an even width and height. Can be accessed in OpenGL 154 * shaders through an external sampler. Does not support mip-maps 155 * cube-maps or multi-layered textures. 156 */ 157 AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420 = 0x23, 158 }; 159 160 /** 161 * Buffer usage flags, specifying how the buffer will be accessed. 162 */ 163 enum AHardwareBuffer_UsageFlags { 164 /// The buffer will never be locked for direct CPU reads using the 165 /// AHardwareBuffer_lock() function. Note that reading the buffer 166 /// using OpenGL or Vulkan functions or memory mappings is still 167 /// allowed. 168 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL, 169 /// The buffer will sometimes be locked for direct CPU reads using 170 /// the AHardwareBuffer_lock() function. Note that reading the 171 /// buffer using OpenGL or Vulkan functions or memory mappings 172 /// does not require the presence of this flag. 173 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL, 174 /// The buffer will often be locked for direct CPU reads using 175 /// the AHardwareBuffer_lock() function. Note that reading the 176 /// buffer using OpenGL or Vulkan functions or memory mappings 177 /// does not require the presence of this flag. 178 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL, 179 /// CPU read value mask. 180 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL, 181 182 /// The buffer will never be locked for direct CPU writes using the 183 /// AHardwareBuffer_lock() function. Note that writing the buffer 184 /// using OpenGL or Vulkan functions or memory mappings is still 185 /// allowed. 186 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4, 187 /// The buffer will sometimes be locked for direct CPU writes using 188 /// the AHardwareBuffer_lock() function. Note that writing the 189 /// buffer using OpenGL or Vulkan functions or memory mappings 190 /// does not require the presence of this flag. 191 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4, 192 /// The buffer will often be locked for direct CPU writes using 193 /// the AHardwareBuffer_lock() function. Note that writing the 194 /// buffer using OpenGL or Vulkan functions or memory mappings 195 /// does not require the presence of this flag. 196 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4, 197 /// CPU write value mask. 198 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4, 199 200 /// The buffer will be read from by the GPU as a texture. 201 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8, 202 /// The buffer will be written to by the GPU as a framebuffer attachment. 203 AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9, 204 /** 205 * The buffer will be written to by the GPU as a framebuffer 206 * attachment. 207 * 208 * Note that the name of this flag is somewhat misleading: it does 209 * not imply that the buffer contains a color format. A buffer with 210 * depth or stencil format that will be used as a framebuffer 211 * attachment should also have this flag. Use the equivalent flag 212 * AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER to avoid this confusion. 213 */ 214 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, 215 /** 216 * The buffer will be used as a composer HAL overlay layer. 217 * 218 * This flag is currently only needed when using ASurfaceTransaction_setBuffer 219 * to set a buffer. In all other cases, the framework adds this flag 220 * internally to buffers that could be presented in a composer overlay. 221 * ASurfaceTransaction_setBuffer is special because it uses buffers allocated 222 * directly through AHardwareBuffer_allocate instead of buffers allocated 223 * by the framework. 224 */ 225 AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1UL << 11, 226 /** 227 * The buffer is protected from direct CPU access or being read by 228 * non-secure hardware, such as video encoders. 229 * 230 * This flag is incompatible with CPU read and write flags. It is 231 * mainly used when handling DRM video. Refer to the EGL extension 232 * EGL_EXT_protected_content and GL extension 233 * GL_EXT_protected_textures for more information on how these 234 * buffers are expected to behave. 235 */ 236 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14, 237 /// The buffer will be read by a hardware video encoder. 238 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16, 239 /** 240 * The buffer will be used for direct writes from sensors. 241 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 242 */ 243 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23, 244 /** 245 * The buffer will be used as a shader storage or uniform buffer object. 246 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB. 247 */ 248 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24, 249 /** 250 * The buffer will be used as a cube map texture. 251 * When this flag is present, the buffer must have a layer count 252 * that is a multiple of 6. Note that buffers with this flag must be 253 * bound to OpenGL textures using the extension 254 * GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 255 */ 256 AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25, 257 /** 258 * The buffer contains a complete mipmap hierarchy. 259 * Note that buffers with this flag must be bound to OpenGL textures using 260 * the extension GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image. 261 */ 262 AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26, 263 264 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1UL << 28, 265 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1UL << 29, 266 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1UL << 30, 267 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1UL << 31, 268 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1UL << 48, 269 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1UL << 49, 270 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1UL << 50, 271 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1UL << 51, 272 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1UL << 52, 273 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1UL << 53, 274 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1UL << 54, 275 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1UL << 55, 276 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1UL << 56, 277 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1UL << 57, 278 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1UL << 58, 279 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1UL << 59, 280 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1UL << 60, 281 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1UL << 61, 282 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1UL << 62, 283 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1UL << 63, 284 } 285 286 /** 287 * Buffer description. Used for allocating new buffers and querying 288 * parameters of existing ones. 289 */ 290 struct AHardwareBuffer_Desc { 291 uint32_t width; ///< Width in pixels. 292 uint32_t height; ///< Height in pixels. 293 /** 294 * Number of images in an image array. AHardwareBuffers with one 295 * layer correspond to regular 2D textures. AHardwareBuffers with 296 * more than layer correspond to texture arrays. If the layer count 297 * is a multiple of 6 and the usage flag 298 * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is 299 * a cube map or a cube map array. 300 */ 301 uint32_t layers; 302 uint32_t format; ///< One of AHardwareBuffer_Format. 303 uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags. 304 uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate() 305 uint32_t rfu0; ///< Initialize to zero, reserved for future use. 306 uint64_t rfu1; ///< Initialize to zero, reserved for future use. 307 } 308 309 /** 310 * Holds data for a single image plane. 311 */ 312 struct AHardwareBuffer_Plane { 313 void* data; ///< Points to first byte in plane 314 uint32_t pixelStride; ///< Distance in bytes from the color channel of one pixel to the next 315 uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to 316 /// the first value of the next row. 317 } 318 319 /** 320 * Holds all image planes that contain the pixel data. 321 */ 322 struct AHardwareBuffer_Planes { 323 uint32_t planeCount; ///< Number of distinct planes 324 AHardwareBuffer_Plane[4] planes; ///< Array of image planes 325 } 326 327 /** 328 * Opaque handle for a native hardware buffer. 329 */ 330 struct AHardwareBuffer; 331 332 static if(__ANDROID_API__ >= 26) 333 { 334 /** 335 * Allocates a buffer that matches the passed AHardwareBuffer_Desc. 336 * 337 * If allocation succeeds, the buffer can be used according to the 338 * usage flags specified in its description. If a buffer is used in ways 339 * not compatible with its usage flags, the results are undefined and 340 * may include program termination. 341 * 342 * Available since API level 26. 343 * 344 * \return 0 on success, or an error number of the allocation fails for 345 * any reason. The returned buffer has a reference count of 1. 346 */ 347 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc, 348 AHardwareBuffer** outBuffer); 349 /** 350 * Acquire a reference on the given AHardwareBuffer object. 351 * 352 * This prevents the object from being deleted until the last reference 353 * is removed. 354 * 355 * Available since API level 26. 356 */ 357 void AHardwareBuffer_acquire(AHardwareBuffer* buffer); 358 359 /** 360 * Remove a reference that was previously acquired with 361 * AHardwareBuffer_acquire() or AHardwareBuffer_allocate(). 362 * 363 * Available since API level 26. 364 */ 365 void AHardwareBuffer_release(AHardwareBuffer* buffer); 366 367 /** 368 * Return a description of the AHardwareBuffer in the passed 369 * AHardwareBuffer_Desc struct. 370 * 371 * Available since API level 26. 372 */ 373 void AHardwareBuffer_describe(const AHardwareBuffer* buffer, 374 AHardwareBuffer_Desc* outDesc); 375 376 /** 377 * Lock the AHardwareBuffer for direct CPU access. 378 * 379 * This function can lock the buffer for either reading or writing. 380 * It may block if the hardware needs to finish rendering, if CPU caches 381 * need to be synchronized, or possibly for other implementation- 382 * specific reasons. 383 * 384 * The passed AHardwareBuffer must have one layer, otherwise the call 385 * will fail. 386 * 387 * If \a fence is not negative, it specifies a fence file descriptor on 388 * which to wait before locking the buffer. If it's negative, the caller 389 * is responsible for ensuring that writes to the buffer have completed 390 * before calling this function. Using this parameter is more efficient 391 * than waiting on the fence and then calling this function. 392 * 393 * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. 394 * If set, then outVirtualAddress is filled with the address of the 395 * buffer in virtual memory. The flags must also be compatible with 396 * usage flags specified at buffer creation: if a read flag is passed, 397 * the buffer must have been created with 398 * AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or 399 * AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN. If a write flag is passed, it 400 * must have been created with AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY or 401 * AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN. 402 * 403 * If \a rect is not NULL, the caller promises to modify only data in 404 * the area specified by rect. If rect is NULL, the caller may modify 405 * the contents of the entire buffer. The content of the buffer outside 406 * of the specified rect is NOT modified by this call. 407 * 408 * It is legal for several different threads to lock a buffer for read 409 * access; none of the threads are blocked. 410 * 411 * Locking a buffer simultaneously for write or read/write is undefined, 412 * but will neither terminate the process nor block the caller. 413 * AHardwareBuffer_lock may return an error or leave the buffer's 414 * content in an indeterminate state. 415 * 416 * If the buffer has AHARDWAREBUFFER_FORMAT_BLOB, it is legal lock it 417 * for reading and writing in multiple threads and/or processes 418 * simultaneously, and the contents of the buffer behave like shared 419 * memory. 420 * 421 * Available since API level 26. 422 * 423 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags 424 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer 425 * has more than one layer. Error number if the lock fails for any other 426 * reason. 427 */ 428 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage, 429 int32_t fence, const ARect* rect, void** outVirtualAddress); 430 431 /** 432 * Unlock the AHardwareBuffer from direct CPU access. 433 * 434 * Must be called after all changes to the buffer are completed by the 435 * caller. If \a fence is NULL, the function will block until all work 436 * is completed. Otherwise, \a fence will be set either to a valid file 437 * descriptor or to -1. The file descriptor will become signaled once 438 * the unlocking is complete and buffer contents are updated. 439 * The caller is responsible for closing the file descriptor once it's 440 * no longer needed. The value -1 indicates that unlocking has already 441 * completed before the function returned and no further operations are 442 * necessary. 443 * 444 * Available since API level 26. 445 * 446 * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if 447 * the unlock fails for any reason. 448 */ 449 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence); 450 451 /** 452 * Send the AHardwareBuffer to an AF_UNIX socket. 453 * 454 * Available since API level 26. 455 * 456 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error 457 * number if the operation fails for any reason. 458 */ 459 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd); 460 461 /** 462 * Receive an AHardwareBuffer from an AF_UNIX socket. 463 * 464 * Available since API level 26. 465 * 466 * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error 467 * number if the operation fails for any reason. 468 */ 469 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer); 470 } 471 472 static if(__ANDROID_API__ >= 29) 473 { 474 /** 475 * Lock a potentially multi-planar AHardwareBuffer for direct CPU access. 476 * 477 * This function is similar to AHardwareBuffer_lock, but can lock multi-planar 478 * formats. The locked planes are returned in the \a outPlanes argument. Note, 479 * that multi-planar should not be confused with multi-layer images, which this 480 * locking function does not support. 481 * 482 * YUV formats are always represented by three separate planes of data, one for 483 * each color plane. The order of planes in the array is guaranteed such that 484 * plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V 485 * (Cr). All other formats are represented by a single plane. 486 * 487 * Additional information always accompanies the buffers, describing the row 488 * stride and the pixel stride for each plane. 489 * 490 * In case the buffer cannot be locked, \a outPlanes will contain zero planes. 491 * 492 * See the AHardwareBuffer_lock documentation for all other locking semantics. 493 * 494 * Available since API level 29. 495 * 496 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags 497 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer 498 * has more than one layer. Error number if the lock fails for any other 499 * reason. 500 */ 501 int AHardwareBuffer_lockPlanes(AHardwareBuffer* buffer, uint64_t usage, 502 int32_t fence, const ARect* rect, AHardwareBuffer_Planes* outPlanes); 503 504 /** 505 * Test whether the given format and usage flag combination is 506 * allocatable. 507 * 508 * If this function returns true, it means that a buffer with the given 509 * description can be allocated on this implementation, unless resource 510 * exhaustion occurs. If this function returns false, it means that the 511 * allocation of the given description will never succeed. 512 * 513 * The return value of this function may depend on all fields in the 514 * description, except stride, which is always ignored. For example, 515 * some implementations have implementation-defined limits on texture 516 * size and layer count. 517 * 518 * Available since API level 29. 519 * 520 * \return 1 if the format and usage flag combination is allocatable, 521 * 0 otherwise. 522 */ 523 int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* desc); 524 525 /** 526 * Lock an AHardwareBuffer for direct CPU access. 527 * 528 * This function is the same as the above lock function, but passes back 529 * additional information about the bytes per pixel and the bytes per stride 530 * of the locked buffer. If the bytes per pixel or bytes per stride are unknown 531 * or variable, or if the underlying mapper implementation does not support returning 532 * additional information, then this call will fail with INVALID_OPERATION 533 * 534 * Available since API level 29. 535 */ 536 int AHardwareBuffer_lockAndGetInfo(AHardwareBuffer* buffer, uint64_t usage, 537 int32_t fence, const ARect* rect, void** outVirtualAddress, 538 int32_t* outBytesPerPixel, int32_t* outBytesPerStride); 539 }